Including Interactive Elements#
Introduction#
Important
Our platform for digital publishing displays books as static web pages. Because of that, features that require a server running in the background are not supported. Please make sure that an object you want to add to a digital version of your book can be handled by a static web site.
All dynamic functionalities must be performed in a browser of anyone who views your book. This is a very powerful solution but has its limitations. Some dynamic features require a server or a database, which do not exist. If a feature cannot be performed in a viewer’s browser, it will not be rendered in your digital book and can even break part of your book of being shown.
Nearly all dynamic functionalities that can be shown in a static web page can be shown in a digital version of your book as well. This includes interactive maps, graphs, charts, diagrams, animations, video or audio players, and even games your readers can play – as long as it doesn’t require a running server.
“Will I Be Able To Use My Pre-Existing Jupyter Notebook?”#
Yes, you will be able to use your pre-existing Jupyter notebook. We can show your Jupyter notebook (data, code and outputs), but we will not execute your code for you. You must execute your notebook and export its outputs in a way described in later parts of these guidelines. This solution gives you great flexibility in generating your book’s contents. This means that you should be able to use the work you have done on your .ipynb file, regardless which Python version you have been using (or maybe you used something completely different instead), what are the libraries that you have chosen, what hardware you operated on (for example you can perform your computations utilizing GPU instead of CPU), etc. It should work as expected, assuming the generated output can be included in a static web page.
Thinking About Longevity#
When preparing your book for publishing, please consider it’s life after the release. Whenever you include a link to an external source, bear in mind that a target of such link might change or cease to exist in the future.
Important
When using hyperlinks to web pages, please archive the exact version of the page you want to link to, archive it using the Internet Archive project and put the archived link as an address of the hyperlink (e.g. to https://web.archive.org/web/1993043000000/lint/to/your/actual/target).
You should also apply this caution when dealing with any other external sources. Whenever you directly or indirectly use a resource that is hosted by a service like YouTube, Vimeo, Sketchfab, Observable, GitHub, Google Drive, Google Sheets, Tableau, etc., you have to take note of it’s terms of service. In general, there is no guarantee that your link to a resource hosted there will stay unchanged. Wherever possible, include static files instead of links to resources.
Non-Dynamic Objects#
Tip
The simplest and best way to include a non-interactive visualization in your book is to insert it as an image.
Say you already have a Jupyter notebook, but instead of incorporating it as a whole in your book you want to include a single visualization generated in it. As an example, let take a the famous Charles Minard’s chart recreated by Amit Amola using Python and Matplotlib. The process of exporting it as an image is very simple, but it depends on which notebook application you are using.
Figure 1: Recreation of Minard’s Chart of Napoleon’s Russian Campaign made by Amit Amola (GPL-3.0 license).
Jupyter Notebook / Google Colab#
In Jupyter Notebook or in Google Colab, just right click on a visualization, save the image and import it in your .docx file as you normally would with an image.
Jupyter Lab#
In Jupyter Lab, you can just drag-and-drop the output of your notebook to the File Browser tab on the left of the screen. Download the object and insert it in your .docx file as you normally would with an image.
Microsoft Office objects#
You can also enrich your book with objects from your MS Word, MS Excel, MS PowerPoint, etc. This includes, among others, Charts, 3D models, WordArts and SmartArts objects. However, just inserting them to your .docx file will not work. Instead, you must save them to a separate file and reference them in your metadata table, at least in the “## Original” field. It is recommended that you take a screenshot of your object and use the image as the “## Digital source” and the “## Paper source” in the metadata table as well. Bear in mind that such screenshots are required to have high quality to be published.
Figure 2: Example of a metadata table referencing an Excel chart.
Figure 3: Excel chart rendered from the metadata table.
Tip
When dealing with Excel charts and similar objects, you should save them to a separate file and insert a metadata table with the “##Original” field pointing to the separate file (e.g. to the .xlsx file) and the “##Digital source” and the “##Paper source” fields pointing to an high-resolution image of the chart.
Dynamic JavaScript Objects#
JavaScript is a language that was specifically designed to run natively in web browsers. This means that all modern web browsers can interpret and run JavaScript code without needing any additional plugins or tools. On the other hand, tools like Jupyter Notebooks are fantastic tools for data analysis and exploration, but they’re not designed for creating elements of interactive web pages.
Using Observable Notebook#
The easiest way to include a JavaScript object, like a map or a graph, is to use the export option of an Observable notebook.
For example, if you would like to include this chart in your book, here are the steps to follow.
Step 1: Click on the “Embed cells” button.
Step 2: Select cells to embed, click “Copy URL only”.
Step 3: In your Word file, create a Metadata table. Make sure it has a a) “##Digital source” field with the URL you’ve copied from the Observable notebook and b) “##Height” field with “height” value from the <iframe> snippet shown at the bottom of the page in Observable. Remember to add appropriate metadata about the author and copyrights.
Result:
Figure 4: Income per capita, population and life expectancy 1800-2005 graph made by Mike Bostock and published under ISC License.
This method should work on almost every visualization as long as the Observable portal supports exporting objects as <iframe>. Some other examples are available here.
Other JavaScript Objects#
If you feel competent in your skills in programming JavaScript, you can try to write your own html file and embed it in your book. This might be an interesting solution to include a custom JavaScript widget or visualization in your book. To embed a custom html file in your book, write the html location as the “##Digital source” in a metadata table.
Figure 5: Locations around the World of University of Luxembourg and De Gruyter.
Important
Please be mindful, that you, as an author, are responsible for the html you include in your book. For example, if you include an unverified script from a doubtful source, you may involuntarily expose your readers to security threats. Other common problems include adding a feature that might not be rendered properly on all devices (e.g. on older browsers or on mobile phones), adding features that currently work but might break in the future or adding elements that negatively impact performance of your digital monography.
Writing code for maps, graphs, diagrams, etc. is a skill on its own. Please refer to separate documentation appropriate for a given topic to have a better understanding of how to construct such elements.
Another challenge is to get and transform data to use in your visualization. Here is an example of fetching a TopoJSON data before constructing a map.
Figure 6: Map of Poland as of April 1938 made by Iwona Rajca, @EveTheAnalyst. See also [a tutorial on making similar maps](https://web.archive.org/web/20221204213018/https:/datawanderings.com/2019/07/08/merging-historical-maps/).Our platform for digital publishing gives you great flexibility regarding the elements you can embed in your book. Nearly every object that can be embedded as a <iframe> html object can be also part of your book. Use this ability with highest responsibility.
Dynamic Objects From Jupyter Notebook#
Jupyter Widgets#
There is a subset of Jupyter interactive visualizations called jupyter-widgets that do not need a server to add interactivity to your book called.
Step1: Copy the html object (in Jupyter notebook select “Widgets” > “Embed Widgets” > “Copy to Clipboard”)
Step 2: paste the copied data into .html file
Step 3: point to .html file in your .docx file
Result:
Jupyter Notebooks As .html#
You can also include the whole .ipynb notebook inside an .docx file. To do that, just export the contents of your .ipynb to .html and refer to this .html file in a metadata table. How to perform the export operation depends on the tool you are using.
In Jupyter notebook, you must click the “File” button in the top left corner of the window and select “Download as” > “HTML (.html)”.
In Jupyter Lab, select “File” > “Save and Export Notebook As…” > “HTML”.
Then just reference the .html file in the metadata table in your .docx file.
Figure 7: Monthly distribution of passengers (1949-1960).
If interactivity works in the stand-alone .html file, it most likely will also work in the digital version of your book.
JupyLight#
To give your readers availability to interact with your code, one option is to use the JupyterLite. Because it runs entirely in the browser and does not need a server, you will be able to include it a digital version of your book.
Important
Although JupyterLite is currently being developed by core Jupyter developers, the JupyterLite project is still unofficial. Not all the usual features available in JupyterLab and the classic Jupyter Notebook will work with JupyterLite, but many already do. There is also no guarantee that JupyterLite will be developed and maintained in the future.
To include a JupyterLite terminal inside your digital page, insert a metadata table referring to the JupyterLite demo hosted on GitHub. You can also choose among available options, e.g. Jupyter Lab vs Jupyter Notebook, Python vs JavaScript, etc. In this example, we do not point to any “## Paper source”, so that our paper version will leave that object out entirely.
Jupyter Lab example
Python example
Here is an exemplary code you can try:
from sklearn import datasets
import matplotlib.pyplot as plt
iris = datasets.load_iris()
_, ax = plt.subplots()
scatter = ax.scatter(iris.data[:, 0], iris.data[:, 1], c=iris.target)
ax.set(xlabel=iris.feature_names[0], ylabel=iris.feature_names[1])
_ = ax.legend(
scatter.legend_elements()[0], iris.target_names, loc="lower right", title="Classes"
)
JavaScript example